Home

MultiXTpm Generic Multiplexer

Open Source/Free Software
MultiXTpm Generic Multiplexer is an application built on top MultiXTpm Application Server.
Its purpose is to provide application level multiplexing of messages arriving from multiple connections into one or more connections, using application data for multiplexing rules.

The main use of such multiplexer is when there is a server application, that for various reasons, can handle a definite number of open connections, and on the other hand the number of client applications and the connection type is not known ahead.

For example, an ISO 8583 Authorization Server is written to support a limited number of connections to ISO 8583 Acquirer Gateways, and these connections must be permanently opened. For this architecture to work, the ISO 8583 Acquirer Gateways must handle hundreds of input connections which must be tunneled / multiplexed in a well known number of output connections to the ISO 8583 Authorization Server.

Another example is from the SMPP (Short Message Peer-to-Peer) world. Many existing SMSC (Short Message Service Centre) servers are built to be connected to ESMEs (External Short Message Entity) using permanently opened connections. This architecture is fine when the number of ESMEs is small, but when the number of ESMEs grows and this number is unknown in advance, as in the case of internet users sending SMSs, there comes a need to use some external system that will handle all the input connections and route all messages thru a smaller number of opened connections.

MultiXTpm Generic Multiplexer is built to help solving such issues and it includes the following features:
  • Can handle theoretically unlimited number of input connections.
  • Can maintain an open connection with clients or a one request connection.
  • Support for input connections arriving thru different TCP ports.
  • Multiplex all requests into a single output connection or into multiple output connections.
  • When configured to support multiple output connections, it load balances all requests between all connections.
  • Can multiplex various types of applications where each application has a different set of rules for multiplexing.
  • Support output queues to the servers with configurable timeouts.
  • Can be customized to support any application level protocol.
  • Support clients that send headerless messages.

In order for MultiXTpm Generic Multiplexer to do its job, the client applications and the servers must adhere to some basic rules:

  • Communications between the peers must be message based, and there must be a field at the beginning of the message, specifying the total length of message. The total length can be inclusive or exclusive of the length field itself.
  • A message received from a client, may contain a header field that the multiplexer may override when forwarding to the server. If configured as so, the multiplexer may override the field but will not add any data to the message.
  • Every message forwarded to the server, must have a header field where the multiplexer stores some data and expects it to be returned in the response exactly as it sent it, it does not have to be at the same position.
  • If the message received from a client does not contain a header, the configuration must include information of the size of the header that the multiplexer can add to the message before the message data. This header must be sent and received back because this is how the multiplexer knows how to route back responses to client applications.

Architecture

MultiXTpm Generic Multiplexer runtime environment comprises of 3 processes at the minimum:
  • MultiXTpm - Application Server, Router, load balancer.
  • Multiplexer Client FE - Listener and communications handler, receivng requests from client applications and forwards them to the Server FE.
  • Multiplexer Server FE - Connection initiator and communications handler. This is the actual multiplexer that tunnels all requests to a definite number of connections. 

Multiplexer Client FE

This process acts as a Listener/Transport handler. It is responsible for the actual communication with all client applications. This process always acts as Listener, it never initiates calls. When a new connection is established, it creates a new session object, it waits for incoming messages and when a full message is received, it is forwarded to MultiXTpm process (in the context of the session created earlier) with a special indication of the a Message Code configured for the input connection. This Message Cdoe is used by the Server FE when selecting the server to forward the message to. MultiXTpm in turn forwards the request to the appropriate Multiplexer Server FE process for the actual tunneling of the message to the remote server. When a response comes from the Multiplexer Server FE process, it is forwarded back to the originator of the request. The connection is kept open, waiting for the next request, or disconnect from the client or an idle timer expires in which case the connection is aborted. This process is multithreaded and all communication activities are in NOWAIT manner, so it does not block on any call, so it can theoretically process unlimited number of connections simultaneously. This process can have more then one instance where each instance can manage a different range of ports. All instances can run on a single machine or can be divided between multiple machines.

Multiplexer Server FE

This process is responsible to all communications and the tunneling of messages to the remote servers. When it starts, it receives from MultiXTpm a list of addresses and ports of remote servers and it tries to connect to each one of them in order to establish a permanent connection. When such a connection is established, it marks the connection as Active. From that point on, every message that it receives from Client Server FE, and that message has a Message Code as configured for the connection, is tunneled to the server through that connection. To enable the association of a response to a request, this process sets (or adds) some value in the header of the message and the server has to send that value back in the response. So when a response is received, using that specific value, the process finds the request, and using the information saved in the request, the response is routed back to the client. It is possible to configure more than one connection to a single server or service. This is done by configuring the same “ForwardingMsgCode” to a set of connections. When this process finds that more than one connection is configured this way, it will always forward new messages to the connection with lowest queue size, this way it load balances all the messages between all the connections. This process forwards the requests as soon as it receives them, it does not wait for responses before forwarding the next requests. When a connection is disconnected for some reason, it waits for a pre configured timeout interval and tries to reconnect for a maximum of preconfigured number of retries.

MultiXTpm

This is the main process within this architecture. When it starts, it reads a preconfigured XML file where all configuration data is stored in. Among other things, it starts the first instances of the other processes. When the other processes are started, it provides them with some configuration data. It provides Multiplexer Client FE the information about the TCP/IP ports to listen on for incoming requests. It also provides Multiplexer Server FE the information about the TCP/IP addresses and ports to connect to remote servers for multiplexing outgoing requests. MultiXTpm's main responsibilities are:
  • Monitor the other processes for unexpected termination. When it realizes that one of the processes has terminated, it restarts it if it is configured to do so.
  • When a new request arrives from Multiplexer Client FE, it routes the request to one or more Multiplexer Server FE processes for handling the request.
  • Monitor the queues for the Multiplexer Server FE processes. Based on configuration data, MultiXTpm maintains a queue for each process.
  • Receiving a response from Multiplexer Server FE processes and forward the responses back to Multiplexer Client FE.
Following is a description of the Data Flow in MultiXTpm Generic Multiplexer.
Each request passes thru few phases starting from connection establishment and ending with the connection closing. Between these two phases the Client is said to be "in a session".
Following is a brief description of the various phases.
  1. The client establishes a connection.
  2. The client sends a request.
  3. Multiplexer Client FE Receives the request and validates its syntax.
  4. The message is forwarded in its entirety using the Message Code configured for the input connection for internal routing purposes. If the request is the first one in the session, it is forwarded to MultiXTpm, otherwise it is forwarded directly to the Multiplexer Server FE process that was previously elected by MultiXTpm on the first call.
  5. MultiXTpm, upon receiving the new request, searches its local configuration data for an entry matching the Message Code specified in the request, it does not scan the message AT ALL. If it finds such an entry, it elects the appropriate Multiplexer Server FE process and queues the message for a later forwarding to that process.
  6. If the queue for that process is empty or its size is below a preconfigured maximum, the message is forwarded immediately to the process.
  7. Upon receiving the request, Multiplexer Server FE searches an opened connection that configured to support the given Message Code and has the lowest queue size among all connections that support the given Message Code. When it finds such a connection, it tunnels the message through that connection.
  8. When a response is received, it is forwarded back to original Multiplexer Client FE who forwarded the request.
  9. When the response from MultiXTpm or Multiplexer Server FE is received, Multiplexer Client FE checks that the connection with the client is still valid and if so, it forwards the response.
  10. The response is sent to the client. At that point the client may elect to close the connection and as a result, Multiplexer Client FE will delete the session object. If the connection is not closed, Multiplexer Client FE will use the same session object for handling future requests.

Multiplexer Configuration

Multiplexer configuration is done thru the xml file located in the runtime directory. Its default name is "TpmConfig.xml".
A description of this file and how to configure it can be found here.
In addition to the standard fields that need to be configured, there are few parameters that are required in order to configure the Multiplexer Links specifically.
The following Link parameters control the multiplexing rules used by the Link (Connection):

Parameter Name Description Default Value
ForwardingMsgCode When configured for Multiplexer Client FE Links, it controls the Message Code to use when forwarding a message to Multiplexer Server FE. When configured for the Multiplexer Server FE  Links, it is used to decide which Link to use when a message with the specified Message Code arrives. 1000
MsgSizeIndicatorLength Each message to be multiplexed must begin with a binary field that specifies the total length of a message. It is only after an entire message is received, that the message is processed. This field specifies the size of this field.
Possible values are:
  • 1 - one byte. This implies that the total message size cannot exceed 255 bytes.
  • 2 - two bytes. This implies that the total message size cannot exceed 64K bytes.
  • 4 - Four bytes. This implies that the total message size cannot exceed 4G bytes.

Any other value specified will cause the Multiplexer throw an exception.

 2
MsgSizeIndicatorIncluded This parameter specifies whether the message size specified in the size field, includes the size field itself.
A value of 1 means that the message size includes the size field.		 0
MsgSizeIndicatorIsBigEndian Since the size field is binary, this parameter specifies if it is stored in network format (Big Endian).
A value of 1 specifies that the size field is stored in network format (Big Endian)		 1
SenderContextOffset When Multiplexer Server FE tunnels a message, it needs to save some information in the message. The server that receives that message must return that information in the response. This is used to associate th response with the request. The value in this parameter specifies where in the message Multiplexer Server FE can save that information and where it should retrieve it from when it receives the response. 5
SenderContextSize This parameter tells Multiplexer Server FE how many bytes in the message are reserved for its context to be saved. 2
ReceiverContextOffset This parameter has meaning in Multiplexer Server FE only if SwapContextOnResponse is specified. In this, before sending a response to the client, Multiplexer Server FE swaps the values in the Sender and Receiver Contexts.
This value specifies where in the message, the Receiver Context is located. 		 3
ReceiverContextSize This value specifies the size for the Receiver Context when SwapContextOnResponse is specified. It must be identical to the SenderContextSize value. 2
SwapContextOnResponse Tells Multiplexer Server FE that the Sender Context and the Receiver Context values should be swapped on response. 1
HeaderIncluded When a client application sends a message that includes a header with space for Multiplexer Server FE to store its context, this value should be set to 1. When there is no such space in the message, Multiplexer Server FE create such a space in front of the message data and its size is specified by HeaderSize. The server that receives the message must be prepared to receive such a message. When a response is received, these extra header bytes are removed before forwarding the response to the client application. 1
HeaderSize This parameter tells Multiplexer Server FE how many bytes to insert in front of the message when the original message does not contain any header to be used it in order to save its Sender Context. 0

Download information

MultiXTpm Application Server is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

MultiXTpm Application Server is distributed in source code format and it supports: Windows OS, Linux, Solaris and HP Nonstop Server OSS.

The source code is packed in ZIP file and can be downloaded from SourceForge.net.

To Access the Download Page at SourceForge.net you may click Here
or
Navigate to http://sourceforge.net/projects/multixtpm

Contact information

For more information, Bug Reports, Feature Requests, and Support Requests, please use:
SourceForge.net tracker
or
SourceForge.net Project Forums
or
MultiXTpm group at Yahoo Groups.
or
you may send an email to: Moshe Shitrit
Home